habiticafandomcom_ru-20200216-history
Программный интерфейс приложения
ВАЖНОЕ ПРИМЕЧАНИЕ ДЛЯ ВСЕХ РАЗРАБОТЧИКОВ: *''Habitica API версии 3 выпущена 21 мая 2016 г.'' *''Версия 2 отключена 30 июля 2016 г. Любые сторонние инструменты всё ещё использующие версию 2 перестали работать после этой даты.'' *''Больше информации по Программному интерфейсу приложения и разделу "Изменения API" в Руководстве для кузнецов.'' ---- Программный интерфейс приложения (API) Habitica позволяет создавать программистам сторонние приложения, расширения, и другие инструменты, которые взаимодействуют с Habitica. С помощью учетных данных пользователя из вкладки Параметры API, программы могут получить ограниченный доступ к аккаунту пользователя Habitica, позволяя им отображать и потенциально изменять пользовательские данные и настройки. API версии 3 21 мая 2016 г. был выпущен Habitica API версии 3. Все сторонние программы должны использовать его. API версии 1 и 2 отключены и более не используются. Следующие ресурсы помогут вам обновить любые написанные вами инструменты или создать новые: *Документация Habitica API версии 3 *The Forge - Официальный блог Habitica для кузнецов: **Руководство по переходу с API v2 на v3 **Обзор изменений API версии 3 - основные различия между версиями 2 и 3 *Гильдия Aspiring Blacksmiths (Habitica Coders) для вопросов и поиску помощи *Репозиторий Habitica на GitHub для помощи и сообщений о проблемах API (напр., ошибки или запутанная документация) Ошибки в документации API Если вы нашли ошибки в документации API, сообщите о них в обсуждении на GitHub или отправьте пулл-реквест по ним. Вы можете подумать, что их быстро исправят, но этот процесс может занимать несколько дней перед тем, как мы загрузим исправления на сайт. Использование API Чтобы использовать API, вы отправляете HTTPS запросы на сервер Habitica. URL запроса определяет тип информации, которую вы хотите получить или тип обновления, которое вы хотите сделать. Поддерживаемые URL-ы перечислены в документации API. Большинство URL-ов содержат переменные, чтобы точнее определить получаемые или обновляемые данные (напр., чтобы указать конкретное задание для изменения). * Названия переменных начинаются с двоеточия, например, :variableName. Это значит, что для подстановки значения нужно заменить всю строку, включая двоеточие. К примеру, маршрут Group - Get group выглядит как https://habitica.com/api/v3/groups/:groupId, и для группы с ID равным 12345678-90ab-40a4-cdef-1234567890ab, вы бы использовали https://habitica.com/api/v3/groups/12345678-90ab-40a4-cdef-1234567890ab * Некоторые маршруты имеют больше одной переменной и их нужно заменять все, например, User - Hatch a pet выглядит как https://habitica.com/api/v3/user/hatch/:egg/:hatchingPotion * Когда переменные относятся к типам контента, вы можете найти соответствующие значения по маршруту Content - Get all available content objects (https://habitica.com/api/v3/content). К примеру, :egg может быть TigerCub, а :hatchingPotion может быть CottonCandyBlue Большинство маршрутов API требуют ID пользователя и токен API для аутентификации, которые вы всегда можете добавить через HTTP заголовки запроса (не пытайтесь указать их каким-либо другим способом) используя ключи x-api-user и x-api-key для ваших ID пользователя и токена API соответственно. Как добавить их в заголовки зависит от того, как вы делаете запросы. Для сценариев командной строки, вы можете использовать соответствующий инструмент curl, чтобы отправлять HTTPS запросы. В таком случае, вы должны форматировать URL и заголовки аутентификации следующим образом: curl https://habitica.com/api/v3/user -s -X GET --compressed -H "Content-Type:application/json" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" Для JavaScript используя jQuery Ajax запрос, ваш код может быть подобен этому: $.ajax({ url: 'https://habitica.com/api/v3/user', type: 'GET', dataType: 'json', cache: false, beforeSend: function(xhr){ xhr.setRequestHeader('x-api-user', '12345678-90ab-416b-cdef-1234567890ab'); xhr.setRequestHeader('x-api-key', '12345678-90ab-416b-cdef-1234567890ab'); }, success: yourFunctionToProcessTheData, error: yourFunctionToReportAnError, }); Каждый маршрут API использует один из HTTP методов, таких как GET, POST, PUT или DELETE, отмечаемых цветными надписями в документации. Важно использовать правильный метод в вашем коде (см. type: 'GET' в примере выше). Разные методы имеют разные механизмы для определения переменных и их значений: Для GET запросов, они указываются в строке запроса. Например, https://habitica.com/api/v3/groups?type=party,guilds Для POST, PUT и DELETE запросов, информация указывается в теле запроса. Способ выполнения этого зависит от того, как вы делаете запросы. В HTML формах, для этого используется такие поля формы как input и textarea. В jQuery есть метод jQuery.post(). Для curl, используйте флаг -d: curl -X POST -d "type=todo&text=New Task Text&notes=Some Notes" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/tasks/user curl -X PUT -d "text=Edited Task Text" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/tasks/7d4a623d-0a2c-48e2-b9d9-feea1fa2d467 curl -X DELETE -d "password=yourPasswordGoesHere" -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" https://habitica.com/api/v3/user API версии 2 Информация в этом разделе относится к API версии 2, который отключен и более не используется. Эта информация оставлена здесь только в виде справки, чтобы помочь вам в обновлении существующих инструментов до API версии 3. Extensions and scripts could use Habitica's up/down scoring system for individual tasks. An example of an extension that leveraged this is the Chrome Extension, which up-scored you for visiting productive websites and down-scored you for visiting procrastination-related websites. Other examples of extensions and scripts that up-scored you for good behavior and down-scored you for bad behavior include various Pomodoro-related tools, the Anki Extension, and GitHabit. For extensions and scripts, Habitica had a simple API for up-scoring and down-scoring third-party Habits. Programmers should have issued an HTTP POST to: /api/v2/user/tasks/{id}/{direction} * {id} is a unique identifier for a task consisting of lowercase letters. Try to make it something simple and straightforward, like 'productivity' or 'fitness', because other services may piggy-back off your task. For example, the Chrome extension down-scores a 'productivity' task when you visit vice-related websites (reddit, 9gag, etc). However, Pomodoro up-scores 'productivity' when you complete a task. So the two services share a single task to score your overall productivity. If the task doesn't yet exist, it is created the first time you POST to this URL. * {direction} is 'up' or 'down' * A POST body consisting of the API token is required For example, this applescript command coupled with a timer can record a + on a habit at regular intervals. Replace xxxxx with your User ID and API key. Change 'productivity' to whatever you want to call your habit. do shell script "curl -X POST—compressed -H 'Content-Type:application/json' -H 'x-api-user: xxxxx' -H 'x-api-key: xxxxx' https://habitica.com/api/v2/user/tasks/'productivity'/up" API версии 1 API версии 1 отключен и более не используется. en:Application Programming Interface fr:Application Programming Interface Категория:Вклад Категория:Расширения, приложения и надстройки